Most experienced software developers are familiar with the everything you know is wrong syndrome during development on the Macintosh. The Macintosh toolbox is very unique, and the Printing Manager is no exception. The following information is intended to describe the Printing Manager in enough detail to support the development of Printing Manager Resource Files (from here on referred to as PMRFs). In addition to the required technical information, user interface guidelines are provided. The Printing Manager architecture provides applications with complete control over the appearance of the Page Setup and Print dialogs. Guidelines are required to preserve the consistency of the user interface. The following sections describe the Printing Manager from two perspectives; the application's, and the PMRF's. However, the information is intended for use by developers of PMRFs. Use of this information by application developers can easily lead to device dependent code, and compatibility problems in the future. Before attempting to write a PMRF, be sure to read the Disclaimer and Required Reading sections.
Disclaimer
The development of a PMRF is not an easy project. Experienced engineers working inside Apple's Print Shop can easily spend six months to a year writing one driver. This is significant considering they have access to the source code of all the existing Apple PMRFs. If you are new to Macintosh, you should expect this time to increase dramatically. Third-party PMRF developers have told me that development of a PMRF with no previous experience could easily take 3 to 5 man/years. Before beginning such a large project , it's important to consider the following restrictions:
PMRFs based on this information will not be compatible with the new Printing Manager architecture that will be provided in a future release of System software (sometime after System 7.0).
There is only limited documentation on this topic. Since applications use the Printing Manager in different ways, compatibility problems are common, and require the abilities of someone skilled in debugging. Although MacDTS is supporting the development of PMRFs, we have limited experience. We will not be able to provide complete answers to all of your questions.
Although all of the Macintosh specific interaction is described, some routines (such as halftoning and line layout ) are considered device-dependent as well as proprietary and are not covered. See the Required Reading section for some ideas on where to find more information.
The current implementation of background printing is considered temporary, and will not be documented for use by PMRF developers. Although some extremely resourceful developers have been able to implement background printing in the current architecture, developers of PMRFs supporting devices that require background printing (i.e. extremely slow devices) should wait for the new Printing Manager architecture.
Printing on the Macintosh
The Printing Manager is designed to provide both the user and the developer with a simple and consistent interface to a wide variety of output devices. The user is given an interface to device selection, document formatting based on characteristics of a given device, and control over the actual print job. Since the Chooser, Page Setup, and Print commands are always available, the application must be ready to handle them at any time.
The Printing Manager was designed with device independence in mind. Instead of each developer writing specific routines to support specific output devices, one common interface can be used for output on all devices. That interface is Quickdraw. Although some developers feel the need to use PostScript (when it is available), most developers can get high quality results just using Quickdraw. On higher resolution devices, the SetRsl opcode of the PrGeneral procedure can be used to give applications access to pixels at device resolution.
The current Printing Manager architecture defines PMRFs to be complete and autonomous. When a user purchases a device, it should come from the manufacturer complete with required PMRF to drive the device. Printer manufacturers can either develop in house, or contract for a PMRF to be written. The idea is to have one PMRF for each device type. Multiple companies offering PMRFs for the same device will only lead to added confusion for the user. Installation of a PMRF should be as simple as dragging the file into your System Folder. In addition, a script can be provided for Apple's Installer application. See Technical Note #75, The Installer and Scripts, for more information on the Installer.
The Application's View
The application's view of the Printing Manager is described in the Printing Manager chapters of Inside Macintosh Volumes II and V. The application calls the Printing Manager to get information about the currently selected device. It also calls the Printing Manager to display the Page Setup and Print dialogs. Once the characteristics of the device are known, the application calls the Printing Manager to obtain a Printing Manager GrafPort. This GrafPort is the application's window to the currently selected device. It responds to the same Quickdraw calls used for drawing on the screen.
Since the document can be sent to the Printing Manager using the same calls, the main task of the application is reformatting the document based on information provided in the print record. Both the physical and printable areas of the page are provided in 72 d.p.i. rectangles. After calling PrStlDialog and before calling PrJobDialog, applications should check the metrics of the document against the current print record. Although applications can tell when Page Setup or Print has been selected, the opening of the Chooser is more subtle. Most applications check immediately after calling PrStlDialog. They also check before calling PrJobDialog, if the metrics have changed, the application should present the Page Setup dialog again, just to confirm the current settings, and then reformat the document before printing.
In addition to the options provided by the PMRF, applications are allowed to extend the Page Setup and Print dialogs, adding their own items. See Technical Note #95, How to Add Items to the Print Dialogs. Dialogs and alerts presented by the PMRF should occupy no more than the top half of the screen of a Macintosh Plus. This is especially important for the Page Setup and Print dialogs, since application extensions could be displayed off-screen. Centering dialogs horizontally is good, but vertical positions should remain constant.
Chooser
Once an output device has been selected, the Chooser conveys this information to the Printing Manager by updating a string resource in the System File providing access for both the Printing Manager and the selected PMRF. Although undocumented, this resource is also used by applications. Another common string resource is the user's network name stored in the System file by the Chooser. The LaserWriter PMRF uses this string in its status dialog.
Although applications shouldn't need to know which printer has been chosen, many applications make assumptions based on the high byte of the wDev field in the print record. The high byte of this field contains a unique ID for every PMRF. Many applications look for the ID of the LaserWriter before sending PostScript. This causes problems for PMRFs of other PostScript devices using their own wDev IDs. Because of these problems, many applications have been revised. However, developers of PMRFs supporting PostScript devices may still need to use the LaserWriter's wDev ID to get the proper results.
Page Setup Dialog
The Page Setup dialog provides the user with control over the characteristics of the document to be printed, including page size, orientation, and scale. It also gives users control over the format of their documents. Rather than create an arbitrary format for a new document, applications can determine the characteristics of the currently selected device, and adjust format accordingly.
Most applications base the size of a new document on the page size provided in the print record. If the user requires a different size, they select the Page Setup item from the File menu to change the page size. The application responds to this by calling the Printing Manager to display the Page Setup dialog of the selected PMRF. When the Printing Manager returns control to the application, it is expected to perform any necessary reformatting. Page Setup is usually done when creating a new document, or after choosing a new device.
Options provided in the Page Setup dialog are considered specific to a particular document, and are persistent. That is, applications that save print records with their documents will remember the state of the options selected in this dialog. When the Page Setup dialog is displayed, this state will be used as the default.
Print dialog
The Print dialog provides the user with control over the current print job including options like page range and number of copies. This dialog is displayed when the user is ready to print a document. When the user selects the Print item from the File menu, the application calls the Printing Manager to display the appropriate dialog. Once control returns to the application, the document is printed based on information provided in the print record. Although the state of the options in this dialog are stored in the print record, they are considered to be specific to the print job and are not persistent. Even applications that save print records cannot maintain the state of these options. Note however that in some cases, an option in the Print dialog may be preserved by the PMRF itself.
The Printing Manager's View
The Printing Manager is a collection of routines that are linked into any application that prints. These routines, commonly referred to as _PrGlue, determine the chosen printer (based on a resource in the System file), and dispatch the calls to the appropriate PMRF. Although all applications require _PrGlue, the glue routines are smart enough to check for the existence of the _Printing trap and call it when it is available.
NOTE
For debugging purposes, it is best to use a Macintosh with System 3.3 or later so
that you can break on the _Printing trap. The longword selectors used by
the trap are defined in the MPW interfaces. Note that the list of selectors defined in Inside
Macintosh is incomplete. If you do not have access to MPW interfaces, contact MacDTS.
The PMRF Concept
A PMRF is a collection of resources, including dialogs, alerts, code resources (type PDEF), as well as the normal system resources (i.e. icons, bundles...). Each PMRF contains the code and resources required to support all of the calls listed in the Printing Manager chapters of Inside Macintosh volumes II and V. This includes both the high and low level interfaces.
The high level interface is implemented via PDEF resources in the PMRF. These resources are compiled code procedures with a dispatch table linked in at the beginning. Although a PDEF can load and execute code from another resource type, the PDEF type is defined and reserved by Apple. Apple defines the size and meaning of each PDEF's jump table. By reserving all PDEF resources, Apple preserves the right to expand the Printing Manager simply by defining new PDEFs. For example, the PDEF resource containing the PrGeneral routine was added after the original PDEF resources were defined. If a particular PMRF does not support the PrGeneral PDEF, the Printing Manager will return an resNotFound error. If your PMRF follows the guidelines for the PDEF resources, it will not be affected by these enhancements.
When the application calls the PrGlue, the glue loads and locks the appropriate PDEF resource, and then jumps to the appropriate entry point. The PDEF code is then free to communicate with the user and/or the device. A PDEF routine can even load and call routines from other PDEF resources. PDEFs for AppleTalk devices, for example, load and call PAP (Printer Access Protocol) routines from another PDEF routine. When the PDEF is through, it returns to the PrGlue which unlocks and unloads the PDEF resource.
The low level interface was implemented via a standard Macintosh driver (i.e. DRVR resource). This interface was originally provided for low memory situations on the 128K Macintosh, and application developers have been encouraged to revise to the high level interface. But not all applications have been revised, and PMRFs are still required to support the interface as documented in Inside Macintosh.
The PrGlue directs low level calls to a standard DRVR resource stored in all Macintosh System files. There is also a modified version of the DRVR stored in the MultiFinder file, for use when MultiFinder is enabled. This driver, named .Print, receives standard Open, Close, and Control calls as defined in the Device Manager Chapter of Inside Macintosh. The .Print driver then redirects the calls to the appropriate PMRF driver.
NOTE
The effect of the .Print DRVR on the resource chain is unpredictable. PMRFs
should not make assumptions about the current resource file.
The csCode and csParams of these Control calls are defined in Inside Macintosh.
Since most applications use the high level interface, some drivers simply convert the low level calls into their high level, PDEF, equivalents. However, application developers that use the low level calls usually expect them to execute faster, so you should make every attempt to increase the performance of these calls.
The file information of a PMRF is similar to that of an application. The PMRF should have a unique creator type (registered with MacDTS), as well as bundle and version information. Whenever possible, the icon for the PMRF should resemble the physical appearance of the device it supports. PMRFs are limited to two file types:
PRES for serial devices connected directly to one of the Macintosh serial ports.
Chooser handles PMRFs of this type by automatically displaying the two
serial port icons (i.e. modem and printer). If your device cannot be selected
via this mechanism, you should not use the PRES file type.
PRER for devices other than directly connected serial devices, and for devices
requiring more configuration than that provided by the PRES file type. For
PMRFs of type PRER, the Chooser will call the PMRFs PACK resource to fill
the device list.
What's in a PMRF
A PMRF is a collection of resources. There is no limitation on the type or number of resources that can be stored in a PMRF. In order for a PMRF to be usable by the System, there are a certain number of resources required. These resources are all owned either by the PDEF code, or by the Chooser. For more information on owned resources, see Inside Macintosh [IM I-109]. Resources owned by the PDEF have IDs in the range -6145 to -8192. The reason for having certain resources be owned by the PDEF is historical. Originally, it was thought that PMRF resources might be moved into the System file using the Installer rather than having them in seperate files. Although not required, the convention exists and should be followed. Resources owned by the Chooser have IDs in the range -4065 to -4096. The following is a list of resources that are used by the System (i.e. Chooser & the Printing Manager). PMRF developers must supply those resources appropriate for their device.
System Resources
BNDL,FREF, ICON,vers These provide an icon to be displayed and version information
for the Finder's Get Info window.
Chooser Resources
GNRL Required for AppleTalk devices. This resource is two bytes in
size. The first byte contains the timeout value (i.e. how long the
connection can remain inactive before closing down), and the
second contains the number of retries desired.
PACK This provides Chooser with information about your device. Code
is also provided in this resource to handle user selections in the
device list [IM IV-216]. This resource is ignored for PMRFs with a
file type of PRES.
STR The Chooser uses string resources to store a wide variety of
information. Although these resources may not be used by a
PMRF, it should provide or preserve them whenever possible.
Failure to do so may cause future compatibility problems with the
Chooser.
The following is a list of 'STR ' resources used by the System as well as the Printing Manager:
File ID Contents
PMRF -4090 Pascal string (i.e. includes length byte) containing the name of the
AppleTalk zone that the selected device resides in.
PMRF -4091 The label that appears above the Chooser's list of devices (i.e. 'Select a
LaserWriter:').
PMRF -4094 Plural device type name (i.e. LaserWriters), for use with the Namer
application (only required for AppleTalk devices).
PMRF -4095 Singular device type name (i.e. LaserWriter).
PMRF -4096 Device type name.
System -8190 Name of the spool folder in the System folder. Can be accessed by
using SysEnvirons [IM V-6] to find the blessed, or System Folder, and
then using this string.
System -8192 File name of the chosen PMRF. This string is used by the Printing
Manager at PrOpen time to determine which PMRF to open.
System -16096 User's network name from the Chooser. May be displayed in status
dialogs.
The following is a list of other resources commonly supplied by a PMRF:
PDEF These are the PMRFs CODE resources. PDEFs 0 and/or 1, 4, 5, and 7, are loaded and
called by the Printing Manager. Each PMRF should provide at least this set of PDEF
resources. Apple PMRFs usually store the PAP (Printer Access Protocol) driver in
PDEF 10, however, this is only a convention, and not required.
DRVR One standard Macintosh Device Manager device driver must be provided by each PMRF.
This driver should have the name .XPrint, and an ID of -8192. This driver will be loaded
and overlaid onto the standard .Print driver that lives in the System file. This way, the
Printing Manager only uses one slot in the unit table.
PAPA These resources generally contain data related to networking. For example, PAPA
resource -8192 contains the PAP address of the currently selected device.
MultiFinder's Resource Flag
When using ResEdit version 1.2 or later, you may have noticed a new checkbox in the Get Info dialog. This checkbox is labeled Printer Driver is MultiFinder Compatible, and is used to change the way PMRF resources are loaded. By default, PMRF resources are marked as System resources, meaning that they will be loaded into the system heap. With the introduction of MultiFinder, it is possible for multiple applications to have the Printing Manager open simultaneously. Since it's not possible for applications to share the resources loaded in the system heap, each application needs a private copy of the PMRF resources. To solve this problem, the PDiMC flag was created. This flag tells the Resource Manager to redirect resources marked for the System heap into the application's heap. This allows applications to spool documents simultaneously. If this feature is not required, the flag can be left clear. Applications will still be able to use the PMRF under MultiFinder, but will be limited to one at a time.
One catch to the PDiMC flag, is that PMRFs using this flag must not add or resize resources in the PMRF. In fact, they cannot make any changes that would require changes to the resource file map. In the process of loading resources into the application heap, the Resource Manager gives each application a private copy of the resource file map as well. If the PMRF did resize a resource, only the last resource map written to the file would be remembered, potentially corrupting the resource file. A PMRF may modify data in resources, as long as their size is not changed.
Chooser Interface
The Printing Manager's relationship with the Chooser is very simple. The Printing Manager counts on Chooser to maintain certain resources in the System file. The Chooser is never called by the Printing Manager, and likewise, the Printing Manager is never called by the Chooser. Although the Chooser does call code from the PACK resource in the PMRF, the Printing Manager is not involved. The only resource required by the Printing Manager is the STR resource containing the name of the currently selected PMRF. When a user selects a PMRF in the Chooser list, Chooser opens the appropriate PMRF and loads its PACK resource.
Background Printing and Print Monitor
The current implementation of background printing is considered temporary, and is very device specific. The Print Monitor is currently only capable of handling spool files generated by the LaserWriter PMRFs (including the IISC). Since Print Monitor's current spool file format will not be extended, PMRF developers are discouraged from attempting to implement background printing at this time. Any attempt to do so would require the implementation of separate Backgrounder and Print Monitor applications. Not only would this require intimate knowledge of MultiFinder, a separate mechanism, coexisting with Print Monitor, would be quite a load on the System. Until something better is provided, PMRF developer's should simply support foreground printing only. Developers will be notified when a standard mechanism for background printing becomes available.
The Print Record
One of the biggest problems with the current Printing Manager architecture is the lack of procedural access to its print record. Unlike other Managers on the Macintosh, the Printing Manager does not have calls to get or set the state of options in the print record. For example, there is no way for an application to enable or disable a feature of particular PMRF (i.e. Smoothing). Although limiting for the developer, in many ways, this is the correct approach. In a truly device independent architecture, the user is the only one that knows what features are available. An application wanting to disable smoothing would have know way of determining whether smoothing was even supported. Even if the application could change the default setting of the feature, the user should still have the last word. If a user enables Smoothing for example, the application should not disable it. Instead of interpreting the contents of the print record, the best approach is to blindly save it into every document. This way, the defaults presented to the user at print time are the same as the last time that document was printed. For new documents, the user can use a template, or just configure the print record the first time they print (via the Page Setup and Print dialogs).
The original print record was designed around the Macintosh's first printer - the ImageWriter. Although the print record was designed with future expansion in mind, many of the field names were specific to dot matrix devices like the ImageWriter. These field names were then documented in Inside Macintosh, and unfortunately, few guidelines were available as to their use.
In time, many developers realized that they could extend the functionality of the ImageWriter PMRF by simply setting key fields in the print record prior to calling PrValidate [IM II-158, V-408]. The ImageWriter PMRF would notice the changes to the print record, and reconfigure itself based on their new values. This worked fine as long as the ImageWriter was the only printer available.
When the LaserWriter became available, the print record had to be reconfigured to handle the needs of the new device. Many of the fields required by the ImageWriter PMRF were not applicable to the LaserWriter. And since the LaserWriter PMRF had no need to spool, many of the fields were left obsolete. For example, since the LaserWriter driver converts Quickdraw into PostScript operators, the iRowBytes, iBandV, and iBandH were not needed. They were then used for other purposes. For example, iRowBytes contains the number of copies selected by the user.
This is were the problems began. Although the most important fields of the print record were maintained (i.e.. rPaper, rPage...), developers could no longer depend on the Inside Macintosh definition of the print record. To complicate things further, some developers discovered that they could enable and disable features by changing values in the print record. This has now become very common. In reality, the print record is a PMRF's global variables. Imagine a PMRF modifying the global variables of your application. It could come as quite a shock. For this reason, Technical Note #122, Device Independent Printing, was released. This Technical Note stated that Apple would no longer support the format of the print record. But certain fields are required for document formatting and could not be abandoned. Third party PMRF developers soon discovered the large number of applications that modified the print record. In an effort to support these applications, many of these developers have attempted to match the format and functionality of the Apple print records. Since the number of fields supported varies between PMRFs, documentation on specific fields of the print record would have to be specific to a particular PMRF. In the new world, engineering will attempt to support everything that works currently. This includes the setting of options by writing to fields in the record and calling PrValidate. This support will only last as long as the old world glue. In an attempt to clear things up, I will document some of the more popular fields used by applications:
The Good
The following fields are supported by all printer drivers, both Apple and third
party, for read-only access.
NOTE
These fields are considered documented, all PMRFs must store
reasonable values into these fields. Failure to do so will cause incorrect
formatting in most applications.
TPrint.PrInfo.rPage Imageable area of the page in 72 dpi coordinates.
TPrint.rPaper Physical area of the page in 72 dpi coordinates.
TPrint.PrStl.wDev[High Byte] Unique device ID for each PMRF.
TPrint.PrStl.feed Feed type currently selected (i.e. feedCut, feedFanfold,
feedMechCut, feedOther).
NOTE
The following two fields, iVRes and iHRes are used by many applications. It is because of
this that they have been included in the Good section. In reality, the values of these
fields are very context dependent. In general, they should be be set to 72 except when a
PrGeneral SetRsl operation has been performed. In this case, these fields should
represent the resolution requested by PrGeneral. Also, when the ImageWriter's Tall
Adjusted feature is enabled, the value of iHRes will be 80 instead of 72.
TPrint.PrInfo.iVRes See NOTE (above)...
TPrint.PrInfo.iHRes See NOTE (above)...
TPrint.PrJob.bJDocLoop Return spool or draft loop.
The following fields support both read and write access:
TPrint.PrJob.iFstPage First page to be printed (From in Page Setup).
TPrint.PrJob.iLstPage Last page to be printed (To in Page Setup).
TPrint.PrJob.iCopies Number of times the document should be sent by the
application. For PMRFs that handle multiple copies internally, this field will always be 1.
TPrint.pIdleProc Pointer to application idle procedure.
TPrint.pFileName Pointer to spool file name.
TPrint.iFileVol Volume reference number for spool file.
TPrint.bFileVers File version number - must be 0.
The Bad
These fields are considered unsupported, and are used differently by different
PMRFs. Use of these fields by applications will lead to serious compatibility
problems in the future.
TPrint.iPrVersion Use PrDrvrVers [IM II-163, V-408] instead.
TPrint.PrStl.iPageV Use the rPaper rectangle instead.
TPrint.PrStl.iPageH
TPrint.PrStl.bPort
TPrint.PrInfoPT.iDev The PT stands for PrivaTe!
TPrint.PrInfoPT.iVRes
TPrint.PrInfoPT.iHRes
TPrint.PrInfoPT.rPage
TPrint.PrXInfo.iBandV
TPrint.PrXInfo.iDevBytes
TPrint.PrXInfo.iBands
TPrint.PrXInfo.bPatScale
TPrint.PrXInfo.bULThick
TPrint.PrXInfo.bULOffset
TPrint.PrXInfo.bULShadow
TPrint.PrXInfo.scan
TPrint.PrJob.fFromUsr
TPrint.PrJob.bJobX
TPrint.PrintX[1..19]
The Ugly
The following is a list of some of the more interesting fields used by Apple
PMRFs. This list is provide to give you an example of storing different kinds of
information into the same print record. You may choose to follow Apple's
example when storing similar types of data. This can help increase application
compatibility.
NOTE
This list was compiled by examining the latest versions of each of the
Apple drivers. Although valuable for PMRF developers, use of this information
by applications developers can lead to major compatibility problems. Applications should
not rely on any fields in the print record beyond those listed in the Good section above.
In the following tables, bit 7 is most significant, Bit 0 is least...
ImageWriter (I & II)
Portrait wDev Bit 1 Set
Landscape wDev Bit 1 Clear
Tall Adjusted wDev Bit 2 Set
50% Reduction wDev Bit 3 Set
No Gaps wDev Bit 4 Set
Best wDev Bit 0 = 1 & bJDocLoop = 1
Faster wDev Bit 0 = 0 & bJDocLoop = 1 = Faster
Draft wDev Bit 0 = 0 & bJDocLoop = 0 = Draft
Automatic feed = 1
Manual feed = 0
ImageWriter LQ
Portrait wDev Bit 1 Set
Landscape wDev Bit 1 Clear
No Gaps wDev Bit 4 Set
100% Reduction wDev Bit 7 & 3 Clear
33% Reduction wDev Bit 7 Set, Bit 3 Clear, Bit 0 Clear
66% Reduction wDev Bit 7 Clear, Bit 3 Set, Bit 0 Clear
Best bJDocLoop = 0, wDev Bit 0 Clear
Faster bJDocLoop = 1, wDev Bit 0 Clear
Draft bJDocLoop = 1, wDev Bit 0 Set
Bidirectional wDev Bit 4 Set
Unidirectional wDev Bit 4 Clear
Automatic feed = 1
Manual feed = 0
1st Sheet
Bin 1 PrintX[1] Bit 1 Clear, Bit 0 Set
Bin 2 PrintX[1] Bit 1 Set, Bit 0 Clear
Bin 3 PrintX[1] Bit 1 Set, Bit 0 Set
Remaining Sheets
Bin 1 PrintX[1] Bit 3 Clear, Bit 2 Set
Bin 2 PrintX[1] Bit 3 Set, Bit 2 Clear
Bin 3 PrintX[1] Bit 3 Set, Bit 2 Set
AppleFax Modem
Portrait wDev Bit 1 Set
Landscape wDev Bit 1 Clear
100% Reduction wDev Bit 3 Clear, Bit 2 Clear
33% Reduction wDev Bit 3 Set, Bit 2 Clear
66% Reduction wDev Bit 3 Clear, Bit 2 Set
Best wDev Bit 0 Set
Faster wDev Bit 0 Clear
Save File wDev Bit 5 Set
LaserWriter (Classic, Plus, NT, NTX)
Reduction/Enlargement iBandH = Scale factor
Portrait wDev Bit 1 Set
Landscape wDev Bit 1 Clear
Font Substitution wDev Bit 0 Set
Text Smoothing wDev Bit 6 Set
Graphics Smooth wDev Bit 2 Set
Faster Bitmap Printing PrintX[6] Bit 6 Set
Flip Horizontal PrintX[6] Bit 1 Set
Flip Vertical PrintX[6] Bit 2 Set
Invert Image PrintX[6] Bit 0 Set
Precision Bitmap Alignment PrintX[6] Bit 4 Set
Larger Print Area PrintX[6] Bit 5 Set
Unlimited Downloadable
Fonts PrintX[6] Bit 7 Set
iCopies Always set to 1
iRowBytes Number of copies selected by user
iBandV 0 = No Cover Page
iBandV 1 = First page is cover page
iBandV 2 = Last page is cover page
feed 2 = Paper Cassette
feed 3 = Manual Feed
PrintX[1] 2 = Color/Grayscale
PrintX[1] 3 = Black & White
LaserWriter IISC
Portrait wDev Bit 1 Set
Landscape wDev Bit 1 Clear
Size 100% iBandV Bit 3 Clear, Bit 2 Clear
75% iBandV Bit 3 Clear, Bit 2 Set
50% iBandV Bit 3 Set, Bit 2 Clear
Exact Bit Images iBandV Bit 4 Set
Text Smoothing iBandV Bit 1 Set
Paper Cassette feed = 1
Hand Feed feed = 0
PrintVars
PrintVars is the location of the Printing Manager's low memory globals. In addition to the print record, there are sixteen bytes of low memory reserved for the Printing Manager. These globals contain information that both the System and the PMRF need to access frequently. The general layout of this area is:
Name Bytes Description
iPrError 2 The OSErr returned by the PrError routine.
bPrFlags 1 The infamous Chooser Bits. They have the following
meaning:
Bit(s) Name Description
0&1 DocLoop Defines the type of print job (i.e.
bSpoolLoop [IM II-151]).
2 ? Reserved
3 ? Reserved
4 OpenedRF Set if PMRF is open
5 FGBG Set if job is foreground
6 ATOK When set, AppleTalk is disabled
7 PrRun Set if okay to switch without Page
Setup warning.
bUser1 1 ?
lUser1 4 ?
lUser2 4 ?
lUser3 4 ?
iPrRefNum 2 Resource Manager reference number of the PMRF. This
is used to access resources from the PMRF.
The Printing GrafPort
When an application is ready to print it opens the Printing Manager, and calls PrOpenDoc. At this point, the Printing Manager creates a GrafPort. Because the Printing Manager has some extra information to store, it extends the GrafPort record in the same way that the Window Manager does. By using the TPrPort record [IM II-150], the Printing Manager can store its GrafPort, and all associated information in one pointer. Because this pointer is maintained by the application, and passed to the Printing Manager during important calls, it is considered global to the PMRF code. The TPrPort record is initialized when an application calls PrOpenDoc [IM II-159, V-408]. PrOpenDoc takes a port pointer as a parameter, and returns a pointer to a TPrPort. Because of this, applications have the choice between allocating their own GrafPort, or letting PrOpenDoc allocate it.
Because there are still popular applications on the market that pass in their own GrafPorts to PrOpenDoc, a PMRF's PrOpenDoc routine must be capable of handling any GrafPort passed. PMRFs should not assume that the GrafPort is color, and should be able to print even if passed a black & white, or Classic Quickdraw GrafPort. There are still popular applications on the market that pass in their own GrafPorts to PrOpenDoc. Much more rare are applications that allocate their own I/O buffers before calling PrOpenDoc. The I/O buffer parameter is used instead of the volume buffer when performing File Manager operations on the spool file. PMRFs that don't spool can safely ignore this parameter.
The Printing Manager intercepts data from Quickdraw by replacing the GrafProcs [IM I-148] of the GrafPort that the application is drawing into. When the application calls a Quickdraw routine to draw something, the Printing Manager's GrafProc is called, and the metrics of the object to be drawn are scaled to the given device. Because the Printing Manager might require the use of Quickdraw drawing operations, the original Quickdraw GrafProcs are maintained in the GProcs field of the TPrPort. In addition to the GPort and GProcs fields of the TPrPort, there are four long words and two booleans. These variables can be used freely by PMRF developers, and their values will be maintained for the duration of the print job.
The Glue
The glue as it's commonly called, is the code your application actually jumps to when you call a Printing Manager routine. When PrOpen is called, the glue first calls PrDrvrOpen to open the appropriate low-level driver, and overlay .Print in the System. Once the driver is loaded, it's safe to assume that the PMRF is open. Subsequent calls through the low-level interface are routed by the glue directly to the low-level driver. Calls made through the high-level interface are dispatched by loading the PDEF resource, and then jumping through the jump table to the appropriate offset. When an application calls PrClose, the PMRF is responsible for closing itself, while the glue takes care of detaching the low-level driver.
The Trap
In System file 3.3, the Printing Manager gained a dispatch trap. Instead of just being linked into the application and called directly, the Printing Manager glue is now executed via a Trap. A 32 bit selector is pushed onto the stack (after the appropriate parameters of course), and the trap is dispatched. The trap is called _PrGlue by Apple (_Printing by some well known debuggers), and is available on all Macintosh CPUs running System 3.3 or later. Even though the trap is now available, you can't be sure that your application will be running on a system that has the trap. Because of this, PrGlue must still be linked into an application that uses the Printing Manager (PrGlue resides in the interface.o library of MPW). This glue now checks for the existance of the _PrGlue trap. If the trap is available, it is used. If not, the old PrGlue code is executed.
The Real Driver
When PrDrvrOpen is called by an application, it will be redirected (by the glue) to your PMRF's low-level driver. This driver is a standard Macintosh device driver, and should support the normal Open, Close, Status, and Control calls. In response to a Device Manager open call, a PMRF driver should respond by storing the version number of the driver into the DCE pointed to by A1 (DCtlQueue+1(A1)).
PrDrvrClose calls the Close routine of your driver. Your close routine should respond by performing all the steps necessary to cleanup the environment. This includes disposing of any memory allocated by the low-level driver, as well as closing the connection to the device (if it is still open).
The Prime routine of your driver should simply return noErr. Usually the Status routine of a PMRF would also return noErr, but there is an exception to this rule. In the case of the ImageWriter driver, the Font Manager makes a Status call to request a font characterization table. The font characterization table is documented in Inside Macintosh [I-225-226]. The original use of this table was to clean up output of text on the ImageWriter by adjusting certain characteristics of font. Unfortunately, the only way to create a font characterization is through trial and error, and printing thousands of test pages. Because of this, use of the font characterization table is strongly discouraged.
The control routine is responsible for implementing the three basic types of control calls defined by the low-level Printing Manager interface. They are iPrBitsCtl, iPrDevCtl, and iPrIOCtl [IM II-163].
iPrBitsCtl is used for simple output of bitmaps. Since no GrafPort is provided by the low-level interface, the iPrBitsCtl call cannot support color PixMaps. There is also no access to the dialogs when using the low-level interface, so users do not have the option of printing landscaped.
iPrDevCtl is used for device control. This call is used when opening and closing documents and pages (i.e. low-level equivalents of Open/CloseDoc/Page). It is also used for sending device independent linefeeds during text streaming.
iPrIOCtl is where the I/O happens, well actually, only the O. The Printing Manager is output only, and in the case iPrIOCtl, the only output type is text. But there are some choices on how the text should be interpreted. In the case of the LaserWriter, the text passed can be sent as text to be printed, or as PostScript text to be interpreted. For example, you can send 'Hello World' to be printed, or you can send '(Hello World)show' to be printed. PMRFs supporting PostScript devices should be ready for these types of calls. In the case of devices with simpler interfaces, like the ImageWriter, text can be printed using the native font of the device, or character code may be sent to actually control the device. Use of these device dependent techniques is discouraged, but some applications still take advantage of these back doors. The most common use of the iPrIOCtl call is to stream text. This means printing text using the best speed of the device, without regard for quality. Many communications applications use the low-level interface as a way to print incoming messages as fast as they are being received. When implementing this call, some effort should be made to increase the performance over its high-level equivalent.
Device Communications
Because of the wide variety of communication methods currently available, it is impossible to provide guidance for all of them here. There are three that Apple can help best with. For serial communications, just read the available documentation listed in the Required Reading section. For AppleTalk devices, you will need to contact Apple Software Licensing for information on licensing the PAP object library. For devices requiring other types of communication, such as parallel interfaces, check the buyer's guide. Many third parties are offering these kind of products, and licensing a finished product is usually much better than building one from scratch. However, documentation is available on designing cards for both the Macintosh SE and Macintosh II computers.
Spooling
When deciding whether or not your PMRF should spool, you should consider the requirements of the device you are supporting. For real time devices, devices requiring data transferred at a fixed rate with no delays, spooling is a must. For PostScript devices, or devices supporting some other page description language, it is sometimes possible for the PMRF to convert the Quickdraw calls into PostScript text on a one by one basis, spooling into memory, or sending immediately to the device. The logical choice for Apple spool files was Quickdraw pictures, but since a PMRF is responsible for despooling the pages it spooled, the format is left to the imagination of the PMRF developer.
There are a couple of other important things to remember about spooling. Before opening a spool file, a PMRF should check the print record for any changes to the pFileName or iFileVol fields. These fields are are writable by applications that want to redirect the spool file to a different volume. The current Apple strategy (to change soon), is to spool to the System disk. But this is not very feasible for floppy based users. Application developers attempting to support these floppy based users better came up with a concept known as spool a page, print a page. It turns out that if you treat each page of a spooled document as a separate document (i.e. call PrOpenDoc/PrCloseDoc for each page of the document), the user would only need space for one page of the document instead of the whole document. Because of this, PMRF developers should still expect to see this behavior from a few applications.
The Code (a.k.a. PDEF Resources)
The code resources in a PMRF that implement the Printing Manager procedures are stored in resources of type PDEF. Since the glue is responsible for loading and calling some of these resources, their type and IDs must be maintained. PDEF resources are basically a CODE resource with a jump table stored before the code. This jump table is used by the glue to find the appropriate Printing Manager routine within the PDEF resource. There are currently five predefined PDEF resources. Each PDEF resource implements a specific number of Printing Manager routines, and the jump table at the beginning of the resource is a fixed size. For example, PDEF 0 is responsible for implementing four Printing Manager routines, and the jump table always contains four entries. A jump table entry consists of a 68000 JMP instruction followed by a pc-relative address to jump to. Because of this, each jump table entry is 4 bytes long (2 for the instruction, 2 for the data). Each routine within the PDEF should end with a 68000 RTS instruction (or equivalent) to return to the original caller. Any PDEF resource with an ID not explicitly defined by this document is reserved by Apple.
Draft Printing Partition [PDEF 0]
This PDEF implements Draft printing. Draft (i.e. immediate) printing means that the data is printed as it is received by the Printing Manager's QDProcs. When printing in Draft mode, the bJDocLoop field of the Print Record should be set to bJDraftLoop, and the PMRF should make every attempt to increase performance (i.e. use a native font in the printer rather than downloading a bitmap from the Macintosh). For PMRFs that support PostScript devices, there may not be a need to spool data to disk. Instead, the data can be converted into PostScript as it is received. All versions of the LaserWriter PMRF (up to 6.0) always use Draft printing (i.e. they only implement the PDEF 0 resource, not PDEF 1).
NOTE
When printing in Draft mode, the PMRF should set the value of bJDocLoop in
the print record to bJDraftLoop.
Procedure Jump Table Comments
Offset
PrOpenDoc 0 Creates a Printing Manager GrafPort
(TPrPort).
PrCloseDoc 4 Disposes of the GrafPort and other
structures created by PrOpenDoc.
PrOpenPage 8 Initializes/reinitializes the fields of
the TPrPort, and prepares for incoming
data.
PrClosePage 12 Finishes printing the current page (if
required). The page should only be
printed if it falls within the range
specified by the iFstPage and iLstPage
fields of the print record.
Spooled Printing Partition [PDEF 1]
This PDEF implements Spooled printing. Spooled (i.e. deferred) printing is done by first spooling a document to disk, and then despooling via a call to PrPicFile (see PDEF 5). The format of the resource is the same as PDEF 0, but these routines write their data to disk instead of sending directly to the device.
NOTE
When printing in Spooled mode, the PMRF should set the value of bJDocLoop
in the print record to bJSpoolLoop.
Procedure Jump Table Comments
Offset
PrOpenDoc 0 Creates a Printing Manager GrafPort
(TPrPort).
PrCloseDoc 4 Disposes of the GrafPort and other
structures created by PrOpenDoc.
PrOpenPage 8 Initializes/reinitializes the fields of
the TPrPort, and prepares for incoming
data.
PrClosePage 12 Finishes spooling the current page (if
required). The page should only be
spooled if it falls within the range
specified by the iFstPage and iLstPage
fields of the print record.
NOTE
A PMRF Must implement at least PDEF 0 or PDEF 1. It can also implement both if multiple quality
modes are supported (i.e. the Draft, Faster, and Best modes of the ImageWriter PMRF). In this case, the
value of the bJDocLoop of the print record determines the PDEF that will be called by the glue. If a
PMRF implements PDEF 1, it must also implement PDEF 5 to be able to despool the data.
PrDialogs Partition [PDEF 4]
This PDEF implements the dialogs presented by the PMRF. These dialogs are displayed by a call to the PrStlDialog and PrJobDialog routines of the Printing Manager. It also contains three routines for creating, validating, and merging print records.
Procedure Jump Table Comments
Offset
PrintDefault 0 Fills the print record handle passed with
default values. The Print Record handle
is allocated by the application before
PrintDefault is called, so the PMRF is
only responsible for installing default
values into the record.
PrStlDialog 4 Displays the Page Setup or Style dialog
which is used to present page layout
options (such as page orientation and
reduction) to the user. These options
usually apply to documents created by the
application after Page Setup.
PrJobDialog 8 Displays the PrintÉ or Job dialog which is
used to present job options (such as # of
Copies and page range) to the user.
PrStlInit 12 This routine is used internally by the
PMRF and is not usually used by an
application. The one time an application
does need to use this routine is when
appending items onto the PrStlDialog using
the technique described in Technical Note
#95, How to Add Items to the Print
Dialogs.
PrJobInit 16 This routine is the same as PrStlInit but
applies to PrJobDialog instead. It is
also documented in Technical Note #95.
PrDlgMain 20 This routine implements the event loop
required by both (modal) print dialogs.
It is also documented in Technical Note
#95.
PrValidate 24 This routine is responsible for validating
an existing print record. Validation is
required to make sure that the specified
print record contains values that are
appropriate for the current PMRF. For
example, the print record of one PMRF may
be saved with a document, and then passed
to the PrValidate routine of a different
PMRF at a later date. At this point, the
PrValidate routine would perform a sanity
check on the fields in the context of the
currently selected PMRF.
PrJobMerge 28 This routine is used by applications that
allow the printing of multiple documents
in one print job. In this case, the Job
dialog is displayed once to get the
options for the current job. After that,
the Style information from each document
is merged into the print record that was
passed to PrJobDialog. This way, each
document will be printed according to the
options specified in the PrJobDialog, but
will maintain the Style information that
was specified when the document was
created.
PrPicFile Partition [PDEF 5]
This PDEF implements the PrPicFile routine [IM II-160, V-408]. This routines is responsible for printing the file spooled by the routines in PDEF 1. This PDEF is only required by PMRFs that implement PDEF 1.
NOTE
Although this PDEF is not required, some applications call PrPicFile without first
checking the value of bJDocLoop. Because of this, it's a good idea to provide a
dummy resource that can be loaded and called by the glue. The PrPicFile
routine doesn't have to do anything except return to the caller. Having the
PDEF resource available will prevent the glue from crashing.
Procedure Jump Table Comments
Offset
PrPicFile 0 Despool the file created by the routines
in PDEF. The file name and location of
the spool file are specified by the
pFileName, iFileVol, and bFileVers fields
of the print record. Since an application
can change these fields, no assumptions
should be made about the name or location
of the spool file.
PrGeneral Partition [PDEF 7]
This PDEF implements the PrGeneral routine [IM V-410] and its associated operations. Since PrGeneral was not part of the original Printing Manager, this PDEF is considered optional. This means that applications can check to see if the call is implemented, without crashing. If the PDEF is not available, the Printing Manager will return a resNotFound error to the application. Although PMRF developers are not required to implemented PDEF 7, it is strongly recommended that they do so. The PrGeneral routine accepts a record containing an opcode to specify the desired operation. If your PMRF does not provide a PDEF 7, the application will receive a resNotFound (-192) error. If you decide to implement PDEF 7 in your PMRF, you still need to decide which opcodes to support. You should try to support all of the opcodes documented in Inside Macintosh, although some of them might not be appropriate for your PMRF. For opcodes that are not supported by your PMRF, you should store the opNotImpl(2) error into the iError field of the PrGeneral parameter block before returning control to the application.
NOTE:
Although the PDEF 7 is not required, many applications now use the
GetRslData and SetRsl opcodes. At the very least, your PMRF should support
these two opcodes.
Procedure Jump Table Comments
Offset
PrGeneral 0 All PrGeneral calls are directed to this
routine regardless of the specified
operation. The PrGeneral routine is
responsible for checking the opcode and
performing the appropriate internal dispatching.
Required Reading
When attempting to implement a PMRF, a developer should be armed with all the pertinent documentation that's available. The type of documentation required is usually based on the type of device to be supported, so the following is a general list of documents that might be useful:
ISBN Title Publisher Description
0-201-05409-1 Inside Macintosh Addison- Wesley
Volume I
0-201-05409-2 Inside Macintosh Addison- Wesley
Volume II
0-201-05409-3 Inside Macintosh Addison- Wesley
Volume III
0-201-05409-4 Inside Macintosh Addison- Wesley Updated information based on the new features of the Macintosh
Volume IV Plus (including List Manager, Time Manager, SCSI Manager...).
0-201-05409-5 Inside Macintosh Addison- Wesley Updated information based on the new features of the Macintosh
Volume V SE and II (i.e. Color Quickdraw).
For developers supporting serial devices...
N/A Z8030 Z-BUS Zilog Information on the SCC chip that lives in most Macintosh CPUs.
SCC/Z8530 SCC (Available from any Zilog sales office)
Serial
Communications
Controller
Technical Manual
For developers supporting AppleTalk devices...
0-201-19257-8 Inside AppleTalk Addison- Wesley Technical information on all of the verious protocals supported by
AppleTalk.
For developers supporting devices connected via NuBus card...
0-201-19256-X Designing Cards Addison- Wesley Technical information on designing and implementing your own
& Drivers for NuBus card for the Macintosh.
Macintosh II and
Macintosh SE
For developers supporting SCSI devices...
(Sorry, nothing yet...)
...and as always, Macintosh Technical Notes! All of 'em! The last word in errata-data...
Learning to Drive...
A Guide To Macintosh Printing Manager Resource Files
À • @ • S B1 B9 B> B@ BE BG BÉ BË B‹ BÒ C7 C9 C> C@ CÀ CÂ CÇ CÉ Cû C‡ D D D D D" D$ DÕ DÖ DÛ D† Ec Ed Ej Ek E» F F F GK GL GP GR GÊ GÑ H˝ H˛ H H¢ I@ IA I] IÜ J O˛ O– R% RJ UA UE Uª U» bC b^ f' f/ f¡ gU gV gi gl gı g« g® gß gû gü h h- h0 h√ h… i i jG jVúôñôñôñôñôñôñôñôñôñôñôñôñôñôñôñôñôñôñôñôñôëôñôñôñèñåñèñèñèñèñåñàñëñÚñôÚñôÚñôÚñôñëÔëÔ
À
• @ •
@
• T jV j˜ j˘ j« j® j jÕ jØ jì k k k k[ kp kr k¡ k¶ k¸ kä kø kú l l¥ l¨ lÏ lß lâ lfl m
m m8 mH mK ml mm mu n1 nB nE no nı nƒ n∏ n‹ nÓ nõ o o o1 o3 o7 o9 oE oL oM p‘ pŸ p pˆ qè r› ró s* s. s> s? s∑ s˝ tå tæ tõ vË vÕ wT we wå wó wô y y+ |N |O |` }≈ú÷ñ÷ëñ÷ëñ÷ë÷ñ÷ëñ÷ëñ÷ëñ÷ëñ÷ëñ÷ëñ÷ë÷æ÷ñ÷ëñ÷ëñ÷ëñ÷ñ÷ëàëàëñ÷æ†÷úàúàú÷ØÓë÷ÓëúëúëÓ÷ëÓë÷Óë @ •
